HMAC Authentication policy

Overview

The HMAC (Hash-based Message Authentication Code) Authentication policy validates inbound API requests against a shared secret using an HTTP signature. When you configure it on a deployed API, the gateway inspects the designated signature header, verifies the HMAC signature against the configured secret and algorithm, and either forwards the request or returns HTTP 401.

This policy is particularly useful for webhook-driven integrations where third-party providers require HMAC-based authentication to confirm message integrity and authenticity.

To create a policy rule and attach it to a deployed API, refer to Creating policy rules and Adding policy rules to deployed APIs. When you select HMAC Authentication as the policy type, complete the HMAC-specific fields described on this page.

Key concepts

HMAC: A mechanism that uses a cryptographic hash function and a shared secret key to produce a signature. Both sender and receiver share the same secret; the receiver recomputes the signature to verify authenticity and integrity.

HTTP signature: A standard for signing HTTP requests by including a signature in a designated header, along with metadata about which headers were signed and which algorithm was used.

Shared secret: A secret key both the API consumer and Boomi APIM Gateway share. The consumer uses it to sign requests; the gateway uses the same key to verify them.

Signature scheme: The header the gateway inspects for the signature: AUTHORIZATION, SIGNATURE, or CUSTOMHEADER.

Enforce headers: Headers the HTTP signature must cover. The gateway rejects requests missing any enforced header with HTTP 401.

Clock skew: The maximum allowed time difference, in seconds, between when the request was signed and when the gateway receives it. Set to 0 to disable.

Expression language (EL): Boomi's expression syntax for referencing runtime values dynamically, usable in the Secret Key field. Refer to Expression Language for available attributes.

Timing

On Request	On Response	On Request Content	On Response Content
X

Configuration fields

When you select HMAC Authentication as the policy type, complete the following fields in the Configuration section. For general steps, refer to Creating policy rules.

Field	Required	Description
Header	Yes	Signature header the gateway inspects. Options: AUTHORIZATION (reads from the Authorization header), SIGNATURE (reads from the Signature header), CUSTOMHEADER (reads from a header you specify). Selecting CUSTOMHEADER reveals the Custom Header Name field.
Secret Key	Yes	Shared secret key the gateway uses to validate the HMAC signature. Enter a plain-text value or an EL expression (for example, \{#context.attributes['hmac-secret']\}). The UI masks the raw value after saving.
HMAC Algorithms	No	One or more HMAC algorithms the gateway accepts. The gateway accepts a request when its signature matches any selected algorithm. Supported values: HMAC_SHA256, HMAC_SHA384, HMAC_SHA512, HMAC_SHA1, HMAC_SHA224.
Enforce Headers	No	Header names the HTTP signature must cover (for example, date, host, digest, content-type, request-target). Leave empty to skip header enforcement.
Clock Skew	No	Maximum allowed time difference in seconds between the request timestamp and gateway time. Enter a non-negative integer. Set to 0 to disable.
Decode Signature	No	When enabled, the gateway base64-decodes the signature before validation.
Strict Mode	No	Controls whether the HTTP signature header values (keyId, algorithm, headers, signature) must be wrapped in double quotes, per the HTTP Message Signatures convention. Enabled by default. When enabled: Signature components are passed as quoted strings: keyId="keyId",algorithm="hmac-sha256",headers="host",signature="signatureEncoded" When disabled: Signature components are passed as unquoted values: keyId=keyId,algorithm=hmac-sha256,headers=host,signature=signatureB64

After saving, consumers must include a valid HMAC signature in every request or the gateway returns HTTP 401 with Invalid HTTP Signature or Unauthorized.

Configuring an HMAC Authentication policy

Watch this video for a comprehensive walkthrough on securing your APIs using the HMAC authentication policy.

HMAC policy configuration examples

Validate a request signed with HMAC-SHA256

The following example configures the policy to validate requests signed using HMAC-SHA256 and the HMAC_Header header scheme. If the signature is missing, incorrect, or uses a different algorithm, the gateway returns a 401 status.

"policy-http-signature": {
    "header": "HMAC_Header",
    "secretKey": "your-shared-secret",
    "algorithms": ["HMAC_SHA256"],
    "clockSkew": 0,
    "decodeSignature": false,
    "strictMode": false
}

Validate with enforced headers

The following example requires the HTTP signature to cover the date, host, and digest enforce headers. If the signature omits any of these headers, the gateway returns a 401 status.

"policy-http-signature": {
    "header": "CUSTOMHEADER",
    "secretKey": "your-shared-secret",
    "algorithms": ["HMAC_SHA256"],
    "enforceHeaders": ["date", "host", "digest"],
    "clockSkew": 0,
    "decodeSignature": false,
    "strictMode": false
}

Validate with clock skew enforcement

The following example accepts requests only if the signature timestamp falls within 30 seconds of the gateway's current time. The gateway rejects requests with a timestamp outside this window with a 401 status. This prevents replay attacks using captured valid signatures.

"policy-http-signature": {
    "header": "CUSTOMHEADER",
    "secretKey": "your-shared-secret",
    "algorithms": ["HMAC_SHA256"],
    "enforceHeaders": ["date"],
    "clockSkew": 30,
    "decodeSignature": false,
    "strictMode": false
}

Validate using a secret from Expression Language

The following example retrieves the shared secret from a runtime context attribute instead of a hard-coded value. If the resolved secret does not match the signature, the gateway returns a 401 status. Refer to Expression Language request for available attributes.

"policy-http-signature": {
    "header": "CUSTOMHEADER",
    "secretKey": "{#context.attributes['hmac-secret']}",
    "algorithms": ["HMAC_SHA256"],
    "clockSkew": 30,
    "decodeSignature": false,
    "strictMode": false
}

Gateway error responses

Condition	HTTP status	Message
Missing signature/ Incorrect HMAC signature	401	HMAC signature mismatch.

Related topics

• Creating policy rules
• Adding policy rules to deployed APIs
• Expression Language